docs: add documentation style guide and linting infrastructure#145
Closed
xijing21 wants to merge 1 commit into
Closed
docs: add documentation style guide and linting infrastructure#145xijing21 wants to merge 1 commit into
xijing21 wants to merge 1 commit into
Conversation
Signed-off-by: xijing21 <xijing@iscas.ac.cn>
Contributor
Reviewer's GuideThis PR introduces a formal documentation style guide and markdown linting infrastructure, wires them into contributor workflows, and adds a CI gate for Markdown quality on the restructure-zh branch. Sequence diagram for the updated documentation contribution and linting workflowsequenceDiagram
actor Contributor
participant VSCode_markdownlint as VSCode_markdownlint
participant markdownlint_cli2 as markdownlint-cli2
participant Repo as GitHub_repo
participant MarkdownLintCI as markdownlint-cli2-action
Contributor->>VSCode_markdownlint: Edit docs/*.md, docs/*.mdx
VSCode_markdownlint-->>Contributor: Inline lint warnings
Contributor->>markdownlint_cli2: npm run lint:md
markdownlint_cli2-->>Contributor: Report markdown issues
Contributor->>markdownlint_cli2: npm run lint:md:fix
markdownlint_cli2-->>Contributor: Auto-fix markdown issues
Contributor->>Repo: git push
Contributor->>Repo: Open pull_request (restructure-zh)
Repo->>MarkdownLintCI: Trigger Markdown Lint workflow
MarkdownLintCI->>markdownlint_cli2: Run markdownlint-cli2 "docs/**/*.{md,mdx}"
markdownlint_cli2-->>MarkdownLintCI: Lint results
MarkdownLintCI-->>Repo: PR status (success/failure)
Repo-->>Contributor: CI gate blocks/allows merge
File-Level Changes
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Hey - I've found 2 issues
Prompt for AI Agents
Please address the comments from this code review:
## Individual Comments
### Comment 1
<location path=".github/workflows/markdown-lint.yml" line_range="3-12" />
<code_context>
+ branches:
+ - restructure-zh
+ paths:
+ - 'docs/**/*.md'
+ - 'docs/**/*.mdx'
+
+jobs:
</code_context>
<issue_to_address>
**suggestion (performance):** The path filter is applied only to pull_request, so pushes touching non-doc files will also trigger the workflow.
Because `paths` is only set under `pull_request`, any push to `restructure-zh` will run markdownlint even if no `docs/` files changed. If you only want linting on documentation changes, consider adding the same `paths` filter under `push` to avoid unnecessary CI runs.
```suggestion
on:
push:
branches:
- restructure-zh
paths:
- 'docs/**/*.md'
- 'docs/**/*.mdx'
pull_request:
branches:
- restructure-zh
paths:
- 'docs/**/*.md'
- 'docs/**/*.mdx'
```
</issue_to_address>
### Comment 2
<location path="DOCUMENTATION_LINTING.zh.md" line_range="15-16" />
<code_context>
+4. [本地使用方式](#4-本地使用方式)
+5. [完整工作流总结](#5-完整工作流总结)
+6. [PR CI 门禁](#6-pr-ci-门禁)
+7. [常见问题与故障排查](#8-常见问题与故障排查)
+8. [配套文件清单](#9-配套文件清单)
+
+## 1. 概述
</code_context>
<issue_to_address>
**issue (bug_risk):** 目录中第 7、8 项的锚点编号与后文标题不一致，可能导致内部链接失效。
目录中第 7、8 项分别链接到 `#8-常见问题与故障排查` 和 `#9-配套文件清单`，而对应标题为 `## 7. 常见问题与故障排查` 和 `## 8. 配套文件清单`，生成的锚点应为 `#7-…` 和 `#8-…`。请将目录中的锚点改为 `#7-常见问题与故障排查` 和 `#8-配套文件清单`，以确保跳转正常。
</issue_to_address>Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.
Comment on lines
+3
to
+12
| on: | ||
| push: | ||
| branches: | ||
| - restructure-zh | ||
| pull_request: | ||
| branches: | ||
| - restructure-zh | ||
| paths: | ||
| - 'docs/**/*.md' | ||
| - 'docs/**/*.mdx' |
Contributor
There was a problem hiding this comment.
suggestion (performance): The path filter is applied only to pull_request, so pushes touching non-doc files will also trigger the workflow.
Because paths is only set under pull_request, any push to restructure-zh will run markdownlint even if no docs/ files changed. If you only want linting on documentation changes, consider adding the same paths filter under push to avoid unnecessary CI runs.
Suggested change
| on: | |
| push: | |
| branches: | |
| - restructure-zh | |
| pull_request: | |
| branches: | |
| - restructure-zh | |
| paths: | |
| - 'docs/**/*.md' | |
| - 'docs/**/*.mdx' | |
| on: | |
| push: | |
| branches: | |
| - restructure-zh | |
| paths: | |
| - 'docs/**/*.md' | |
| - 'docs/**/*.mdx' | |
| pull_request: | |
| branches: | |
| - restructure-zh | |
| paths: | |
| - 'docs/**/*.md' | |
| - 'docs/**/*.mdx' |
Comment on lines
+15
to
+16
| 7. [常见问题与故障排查](#8-常见问题与故障排查) | ||
| 8. [配套文件清单](#9-配套文件清单) |
Contributor
There was a problem hiding this comment.
issue (bug_risk): 目录中第 7、8 项的锚点编号与后文标题不一致，可能导致内部链接失效。
目录中第 7、8 项分别链接到 #8-常见问题与故障排查 和 #9-配套文件清单，而对应标题为 ## 7. 常见问题与故障排查 和 ## 8. 配套文件清单，生成的锚点应为 #7-… 和 #8-…。请将目录中的锚点改为 #7-常见问题与故障排查 和 #8-配套文件清单，以确保跳转正常。
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
covering Markdown syntax, Chinese typography, tables, code blocks,
links, images, and Docusaurus-specific conventions
checking, auto-fix, and PR CI gate configuration
setup to PR workflow
Summary by Sourcery
Introduce a formal documentation style guide and markdown linting workflow for the RuyiSDK docs repository, and integrate these into contributor guidelines and CI.
Build:
CI:
Documentation: